DeepWiki

05.a - ntfy-Integration-&-Message-Broker

Relevant source files

Purpose & ScopeLink copied!

This document describes how godeep.wiki uses ntfy.sh as an event-driven message broker to coordinate the automation pipeline. ntfy.sh serves as the central communication hub that triggers repository cloning when customers complete both payment and GitHub connection. The system sends two types of notifications: payment confirmations from Stripe webhooks and installation confirmations from GitHub OAuth callbacks. Automation scripts subscribe to these notifications and execute the cloning pipeline.

For details on what happens after notifications are received, see Repository Cloning Automation. For the automation script implementations, see Automation Scripts.

The system uses ntfy.sh, a simple HTTP-based pub/sub notification service, as its message broker. This architectural choice eliminates the need for a database or complex message queue infrastructure. Notifications are sent via HTTP POST requests and received by scripts that subscribe using ntfy subscribe.

CharacteristicBenefit
No Authentication RequiredSimplifies integration; no OAuth or API keys needed for basic usage
HTTP-BasedEasy to send notifications from any environment (Vercel serverless functions, bash scripts)
Real-Time StreamingScripts receive notifications immediately via SSE (Server-Sent Events)
Zero InfrastructureNo need to manage message queues, databases, or polling mechanisms
Topic-Based RoutingSimple topic names enable logical separation of notification streams

The trade-off is that ntfy.sh provides no message persistence beyond basic retention and no delivery guarantees for offline subscribers.

Sources: Overall system architecture analysis, scripts/ntfy-godeep-automation.sh L1-L151

The system uses a custom topic name stored in the NTFY_TOPIC environment variable. The production topic follows this pattern:

topic-XXXXXXXX

The topic name includes:

  • Namespace prefix: klaudioz-codex-alerts (identifies the system owner)
  • Random suffix: 8sd7fg098sd7g2nkd (provides obscurity to prevent unauthorized subscriptions)
VariableLocationPurposeDefault
NTFY_TOPICVercel environmentTopic name for production notificationsgodeep-wiki-payments
NTFY_TOPIC (script)Hardcoded in scriptTopic the automation script subscribes totopic-XXXXXXXX

Important: The NTFY_TOPIC value in the Vercel environment must match the hardcoded value in the automation scripts. If they differ, notifications will not reach the automation pipeline.

Sources: app/api/webhooks/stripe/route.ts L62

app/api/auth/github/callback/route.ts L114

scripts/ntfy-godeep-automation.sh L6

Diagram: Message Flow from Notification Sources to Consumers

The system sends two notifications per customer workflow:

  1. Step 1: Payment Received - Triggered by Stripe webhook when checkout.session.completed event occurs
  2. Step 2: GitHub Connected - Triggered by GitHub OAuth callback when installation_id is received

Only the Step 2 notification triggers automation. The Step 1 notification serves as an alert for manual correlation.

Sources: app/api/webhooks/stripe/route.ts L48-L82

app/api/auth/github/callback/route.ts L99-L138

Sent from app/api/webhooks/stripe/route.ts L70-L79

:

Diagram: Payment Notification Structure

FieldSourceExample Value
Amountsession.amount_total / 100$10.00
Customersession.customer_email or session.customer_details?.emailuser@example.com
Match IDsession.id.slice(-12)XYZ789ABC123
Timenew Date().toLocaleString('en-US', {timeZone: 'America/New_York'})1/15/2024, 3:45:12 PM

The Match ID (last 12 characters of the Stripe session_id) enables manual correlation between payment and GitHub connection events.

Sources: app/api/webhooks/stripe/route.ts L63-L79

Sent from app/api/auth/github/callback/route.ts L120-L132

:

Diagram: GitHub Connection Notification Structure

FieldSourceExample Value
Installation IDsearchParams.get("installation_id")12345678
CustomeruserData.email or userData.loginuser@example.com
Match IDstripeSessionId.slice(-12) (from decoded state)XYZ789ABC123
Timenew Date().toLocaleString('en-US', {timeZone: 'America/New_York'})1/15/2024, 3:46:30 PM

The Installation ID is the critical piece of data that automation scripts extract to generate access tokens and clone repositories.

Sources: app/api/auth/github/callback/route.ts L113-L132

Diagram: Match ID Correlation Flow

The Match ID (last 12 characters of session_id) appears in both notifications, enabling manual verification that payment and GitHub connection belong to the same customer. This is critical because:

  1. The system has no database to automatically link records
  2. The owner must verify payment before processing repositories
  3. Logs can be searched for the Match ID to find the corresponding Stripe session_id

Match ID Extraction:

Sources: app/api/webhooks/stripe/route.ts L67-L68

app/api/auth/github/callback/route.ts L39-L118

The automation script subscribes to ntfy using the ntfy subscribe command:

ntfy subscribe "$TOPIC" | while read -r line; do    # Process each notification as JSONdone

From scripts/ntfy-godeep-automation.sh L39

Each notification arrives as a JSON object with this structure:

{  "id": "unique_notification_id",  "time": 1705345512,  "event": "message",  "topic": "topic-XXXXXXXX",  "message": "✅ GitHub Connected!\n\n🔑 Installation ID: 12345678\n...",  "title": "Step 2: GitHub Connected - GoDeep.wiki",  "priority": 5,  "tags": ["white_check_mark", "rocket"]}

The automation script filters notifications by title and extracts the installation_id:

Diagram: Notification Processing Logic

The extraction happens at scripts/ntfy-godeep-automation.sh L48-L53

:

if echo "$title" | grep -q "GitHub Connected\|GitHub Installation"; then    # Extract Installation ID from message (macOS compatible)    installation_id=$(echo "$message" | grep -o 'Installation ID: [0-9]*' | grep -o '[0-9]*$')fi

Sources: scripts/ntfy-godeep-automation.sh L39-L53

Code LocationNotification TypeTrigger Event
app/api/webhooks/stripe/route.ts L70-L79Step 1: Payment Receivedcheckout.session.completed Stripe webhook event
app/api/auth/github/callback/route.ts L123-L132Step 2: GitHub ConnectedGitHub OAuth callback with installation_id present
Code LocationPurpose
scripts/ntfy-godeep-automation.sh L39Subscribe to ntfy topic using SSE stream
scripts/ntfy-godeep-automation.sh L41-L42Parse JSON fields (message, title) using jq
scripts/ntfy-godeep-automation.sh L49Filter for GitHub installation notifications
scripts/ntfy-godeep-automation.sh L53Extract installation_id using regex
Code LocationConfiguration Item
scripts/ntfy-godeep-automation.sh L6Hardcoded topic: topic-XXXXXXXX
app/api/webhooks/stripe/route.ts L62Read NTFY_TOPIC from environment, fallback: godeep-wiki-payments
app/api/auth/github/callback/route.ts L114Read NTFY_TOPIC from environment, fallback: godeep-wiki-payments

Sources: All files referenced in this section

HTTP Headers for ntfy.sh POST RequestsLink copied!

Both notification sources use the same header pattern:

HeaderPurposeExample Values
Content-TypeMessage formattext/plain
TitleNotification title (displayed in apps)"Step 1: Payment Received - GoDeep.wiki"
PriorityNotification urgency"high" (value: 4-5 on ntfy scale)
TagsEmoji tags for visual identificationPayment: "moneybag,tada"GitHub: "white_check_mark,rocket"

The ntfy.sh service interprets these headers to format notifications in subscriber clients (mobile apps, desktop apps, web interface).

Sources: app/api/webhooks/stripe/route.ts L70-L77

app/api/auth/github/callback/route.ts L123-L130

The system logs errors but does not retry failed notifications:

Stripe Webhook Handler app/api/webhooks/stripe/route.ts L70-L81

:

await fetch(`https://ntfy.sh/${ntfyTopic}`, { /* ... */ })console.log(`📲 Notification sent to ntfy.sh/${ntfyTopic}`)
  • No try-catch around the fetch
  • Errors propagate to Stripe webhook response handler

GitHub Callback Handler app/api/auth/github/callback/route.ts L122-L137

:

try {    await fetch(`https://ntfy.sh/${ntfyTopic}`, { /* ... */ })    console.log(`Notification sent to ntfy.sh/${ntfyTopic}`)} catch (error) {    console.error("Failed to send ntfy notification:", error)}
  • Errors are caught and logged
  • OAuth flow continues even if notification fails

If notification delivery fails:

  • Payment notification failure: Owner receives no alert about new payment (must check Stripe dashboard manually)
  • GitHub notification failure: Automation does not trigger; owner must manually process repository using admin panel

The system prioritizes user experience (completing OAuth flow) over notification reliability.

Sources: app/api/webhooks/stripe/route.ts L70-L82

app/api/auth/github/callback/route.ts L122-L138

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

05.a - ntfy-Integration-&-Message-Broker | DeepWiki | godeep.wiki